/**
 * Place holder for copyright, needs to be replaced before release.
 */
package com.softao.ming.gwt.ui.client;

import com.google.gwt.user.client.ui.Widget;

/**
 * Handlers the layout of the page.
 * <p>
 * The implementation of this layout defines the place holders, and the view can
 * be added to the place holder to show up, or if there are no views added, the
 * place holder can be put as hidden.
 * <p>
 * The place holder id and it's type (pane, folder and stack) are predefined.
 */
public interface IPageLayout {
	/** editor area contributes the client area of the page. */
	public static String ID_EDITOR_AREA = "com.softao.ming.gwt.ui.editorss";

	/**
	 * Global area which is located left to the editor area. The content of this
	 * area is not related with the content of the editor area.
	 */
	public static String ID_GLOBAL_LEFT_AREA = "com.softao.ming.gwt.ui.globalLeftArea";

	/**
	 * Global area which is located right to the editor area. The content of
	 * this area is not related with the content of editor area.
	 */
	public static String ID_GLOBAL_RIGHT_AREA = "com.softao.ming.gwt.ui.globalRightArea";

	/**
	 * Context area. the view in this area will be refreshed/ notified when the
	 * editor content changed.
	 */
	public static String ID_CONTEXT_AREA = "com.softao.ming.gwt.ui.contextArea";

	/** Commercial views showing in this area. */
	public static String ID_COMMERCIAL_AREA = "com.softao.ming.gwt.ui.commercialArea";

	/**
	 * @param areaId
	 * @return <code>true</code> if the area with specified id is visible.
	 */
	public boolean isAreaVisible(String areaId);

	/**
	 * @param areaId
	 * @param visible
	 */
	public void setAreaVisible(String areaId, boolean visible);

	/**
	 * @param areaId
	 * @return <code>true</code> if the area will be implemented as stacked
	 */
	public boolean isAreaStacked(String areaId);

	/**
	 * @param areaId
	 * @param stacked
	 */
	public void setAreaStacked(String areaId, boolean stacked);

	/**
	 * @return the special id for editor area.
	 */
	public String getEditorArea();

	/**
	 * @return <code>true</code> if editor area is visible.
	 */
	public boolean isEditorAreaVisible();

	/**
	 * By default, the editor area is visible.
	 * 
	 * @param visible
	 *            <code>true</code> to show editor area.
	 */
	public void setEditorAreaVisible(boolean visible);

	/**
	 * Shows the view in the specified area. If the area does not exist, nothing
	 * happen.
	 * 
	 * @param viewId
	 *            the identifier of the view to be added
	 * @param areaId
	 *            the area where the specified view to be added
	 */
	public void showView(String viewId, String areaId);

	/**
	 * Hides the view from the layout.
	 * <p>
	 * If this is the last view of the area, the area will be hide
	 * automatically.
	 * 
	 * @param viewId
	 */
	public void hideView(String viewId);

	/**
	 * Removes the view from the view has been added before; otherwise, nothing
	 * to do.
	 * 
	 * @param viewId
	 */
	public void removeView(String viewId);
	
	/**
	 * @param viewId
	 * @return the id of the area, where the view specified by
	 *         <code>viewId</code> lies in.
	 */
	public String getViewArea(String viewId);
	
	/**
	 * @return the widget of this layout.
	 */
	public Widget getLayoutWidget();
	
}
